Passport Verification API

This document outlines the details of the Passport Verification API.

API Description

Objective

The Passport Verification API authenticates a user by verifying their identity details against the central database maintained by the Ministry of External Affairs (Passport Seva).

Input	Output
The name and the passport details of the customer.	The outcome of comparing the input details with the information retrieved from the matching passport record.

API URL

https://ind-verify.hyperverge.co/api/verifyPassport

API Endpoint

verifyPassport

Overview

The Passport Verification API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the Passport Verification API.

API Request Details

Method - POST

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	The application ID shared by HyperVerge	Not Applicable - this is a unique value
appKey	Mandatory	The application key shared by HyperVerge	Not Applicable - this is a unique value
transactionId	Mandatory	The unique ID for the customer journey	Not Applicable - this is a unique value related to a transaction in your application

Input

The following table provides the details of the parameters required for the Passport Verification API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
fileNo	Mandatory	string	The passport reference file number.	Not Applicable	Not Applicable
dob	Mandatory	string	The date of birth of the customer.	Not Applicable	Not Applicable
doi	Mandatory	string	The date of issue of the passport.	Not Applicable	Not Applicable
passportNo	Mandatory	string	The passport number of the customer.	Not Applicable	Not Applicable
name	Mandatory	string	The name of the customer.	Not Applicable	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Passport Verification API:

curl --location --request POST 'https://ind-verify.hyperverge.co/api/verifyPassport' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "fileNo": "<passport_reference_file_number>",
    "dob": "<Date_of_Birth>",
    "doi": "<Date_of_issue>",
    "passportNo": "<Passport_Number>",
    "name": "<Name_on_Passport>"
}'

Success Response

The following is a sample success response from the Passport Verification API:

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "applicationDate": "10/10/1000",
        "dateOfIssue": {
            "dispatchedOnFromSource": "10/10/1000",
            "dateOfIssueMatch": true
        },
        "passportNumber": {
            "passportNumberFromSource": "12345678",
            "passportNumberMatch": true
        },
        "name": {
            "nameMatch": true,
            "surnameFromPassport": "SAMPLE",
            "nameScore": 1,
            "nameFromPassport": "SAMPLE SAMPLE"
        },
        "typeOfApplication": "SAMPLE"
        }
}

Failure Response

The following is a sample response from the Passport Verification API when no matching record is found for the provided input:

{
  "status": "failure",
  "statusCode": "422",
  "error": "Invalid value passed for an input"
}

info

Although the error message reads "Invalid value passed for an input", this response indicates that no matching record was found in the database for the provided details. The input values themselves may be valid.

Error Responses

The following are the sample error responses for the Passport Verification API:

Missing File Number

{
  "status": "failure",
  "statusCode": "400",
  "error": "fileNo is not allowed to be empty"
}

Missing Passport Number

{
  "status": "failure",
  "statusCode": "400",
  "error": "passportNo is not allowed to be empty"
}

Missing Date of Birth

{
  	"status": "failure",
  	"statusCode": "400",
	  "error": "dob is required"
}

Invalid Input for Date of Birth

{
  "status": "failure",
  "statusCode": "400",
  "error": "dob must be a number of milliseconds or valid date string"
}

Record Not Found

{
  "status": "failure",
  "statusCode": "422",
  "error": "Invalid value passed for an input"
}

Server Error

{
  "status": "failure",
  "statusCode": "500",
  "error": "Unexpected Server Error"
}

Service Unavailable

{
  "status": "failure",
  "statusCode": "504",
  "error": "Govt. database service unavailable"
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message. The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	fileNo is not allowed to be empty	The fileNo in the request contains no value.	Provide a valid passport reference file number in the request
400	passportNo is not allowed to be empty	The passportNo is a mandatory input in the request.	Provide a valid passport number in the request
400	dob is required	The dob parameter is a mandatory input in the request.	Provide a valid date of birth in the request
400	fileNo is required	The fileNo is a mandatory input in the request.	Provide a valid passport reference file number in the request
400	dob must be a number of milliseconds or valid date string		Provide the date of birth as a valid date string or number of milliseconds
422	Invalid value passed for an input	No matching record was found in the database for the provided input. This does not indicate an invalid input, but rather the absence of a matching passport record.	Verify that the provided passport details are correct and correspond to an existing record
500	Unexpected Server Error	There is an issue with the service. Kindly contact the HyperVerge Team for support.	Contact the HyperVerge team for investigation and resolution
504	Govt. database service unavailable	The service is currently unavailable. Kindly retry the request in some time.	Retry the request after some time. If the issue persists, contact the HyperVerge team